home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / p_man / cat3 / Xm / XmeClipboardSource.z / XmeClipboardSource
Text File  |  1998-10-30  |  14KB  |  199 lines
  1.  
  2.  
  3.  
  4.      XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee((((3333XXXX))))    UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV    XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee((((3333XXXX))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.           XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee - A toolkit function that places data on
  10.           the clipboard
  11.  
  12.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.           #include <Xm/Xm.h>
  14.           BBBBoooooooolllleeeeaaaannnn XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee(
  15.           WWWWiiiiddddggggeeeetttt wwwwiiiiddddggggeeeetttt,
  16.           XXXXttttEEEEnnnnuuuummmm oooopppp,
  17.           TTTTiiiimmmmeeee ttttiiiimmmmeeee);
  18.  
  19.      VVVVEEEERRRRSSSSIIIIOOOONNNN
  20.           This page documents Motif 2.1.
  21.  
  22.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  23.           XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee places widget data on the clipboard,
  24.           using the Motif clipboard interface.  If there is an owner
  25.           of _C_L_I_P_B_O_A_R_D__M_A_N_A_G_E_R, calling XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee produces
  26.           undefined results.
  27.  
  28.           This reference page uses the term "the conversion routines
  29.           associated with widget _w_i_d_g_e_t." Whenever you see that term,
  30.           it means that XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee is making the following
  31.           sequence of calls:
  32.  
  33.              1. Calls the application's XXXXmmmmNNNNccccoooonnnnvvvveeeerrrrttttCCCCaaaallllllllbbbbaaaacccckkkk procedures,
  34.                 if any.
  35.  
  36.              2. Calls the source widget's ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc trait method.
  37.                 (ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc is one of the trait methods of the
  38.                 _X_m_Q_T_t_r_a_n_s_f_e_rtrait.)  However, if any
  39.                 XXXXmmmmNNNNccccoooonnnnvvvveeeerrrrttttCCCCaaaallllllllbbbbaaaacccckkkk procedure returns XXXXmmmmCCCCOOOONNNNVVVVEEEERRRRTTTT____DDDDOOOONNNNEEEE or
  40.                 XXXXmmmmCCCCOOOONNNNVVVVEEEERRRRTTTT____RRRREEEEFFFFUUUUSSSSEEEE, then XXXXmmmmeeeePPPPrrrriiiimmmmaaaarrrryyyySSSSoooouuuurrrrcccceeee will not call
  41.                 ccccoooonnnnvvvveeeerrrrttttPPPPrrrroooocccc.
  42.  
  43.           If the _s_e_l_e_c_t_i_o_n member is _C_L_I_P_B_O_A_R_D and the _t_a_r_g_e_t member
  44.           is ____MMMMOOOOTTTTIIIIFFFF____CCCCLLLLIIIIPPPPBBBBOOOOAAAARRRRDDDD____TTTTAAAARRRRGGGGEEEETTTTSSSS or
  45.           ____MMMMOOOOTTTTIIIIFFFF____DDDDEEEEFFFFEEEERRRRRRRREEEEDDDD____CCCCLLLLIIIIPPPPBBBBOOOOAAAARRRRDDDD____TTTTAAAARRRRGGGGEEEETTTTSSSS, then XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee
  46.           sets the value of the _p_a_r_m member of the
  47.           XXXXmmmmCCCCoooonnnnvvvveeeerrrrttttCCCCaaaallllllllbbbbaaaacccckkkkSSSSttttrrrruuuucccctttt to the value of the _o_p argument.
  48.  
  49.           XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee makes the following sequence of calls:
  50.  
  51.              1. XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee asks the conversion routines
  52.                 associated with widget _w_i_d_g_e_t to convert the _C_L_I_P_B_O_A_R_D
  53.                 selection to ____MMMMOOOOTTTTIIIIFFFF____CCCCLLLLIIIIPPPPBBBBOOOOAAAARRRRDDDD____TTTTAAAARRRRGGGGEEEETTTTSSSS.
  54.  
  55.              2. For each returned target, XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee asks the
  56.                 conversion routines associated with widget _w_i_d_g_e_tto
  57.                 convert the _C_L_I_P_B_O_A_R_D selection to that target.
  58.                 XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee then calls XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddCCCCooooppppyyyy to copy
  59.                 the converted data to the clipboard.
  60.  
  61.  
  62.  
  63.      Page 1                                         (printed 10/24/98)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee((((3333XXXX))))    UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV    XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee((((3333XXXX))))
  71.  
  72.  
  73.  
  74.              3. XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee asks the conversion routines
  75.                 associated with widget _w_i_d_g_e_t to convert the _C_L_I_P_B_O_A_R_D
  76.                 selection to ____MMMMOOOOTTTTIIIIFFFF____DDDDEEEEFFFFEEEERRRRRRRREEEEDDDD____CCCCLLLLIIIIPPPPBBBBOOOOAAAARRRRDDDD____TTTTAAAARRRRGGGGEEEETTTTSSSS.
  77.  
  78.              4. If any of the conversion routines associated with
  79.                 widget _w_i_d_g_e_treturn a target, XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee asks
  80.                 the widget to convert the _C_L_I_P_B_O_A_R_D selection to the
  81.                 ____MMMMOOOOTTTTIIIIFFFF____SSSSNNNNAAAAPPPPSSSSHHHHOOOOTTTTtarget.  The responding conversion
  82.                 routine is expected to save a snapshot of the data and
  83.                 to return a distinguisher atom that uniquely
  84.                 identifies the snapshot.
  85.  
  86.              5. XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee places each deferred target on the
  87.                 clipboard by name, using XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddCCCCooooppppyyyy.
  88.  
  89.              6. If the _o_p argument is XXXXmmmmMMMMOOOOVVVVEEEE and the data is
  90.                 successfully transferred, XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee asks the
  91.                 conversion routines associated with widget _w_i_d_g_e_t to
  92.                 convert the _C_L_I_P_B_O_A_R_D selection to the _D_E_L_E_T_E target.
  93.  
  94.           In addition, XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee establishes a callback that
  95.           is automatically called whenever a request is made to
  96.           convert data to a deferred target.  This callback is
  97.           responsible for converting snapshot data to a particular
  98.           target.  Here is the sequence of calls that the callback
  99.           makes:
  100.  
  101.              1. The callback asks the conversion routines associated
  102.                 with widget _w_i_d_g_e_tto convert the snapshot data to that
  103.                 target, using as the _s_e_l_e_c_t_i_o_nthe distinguisher atom
  104.                 returned from the ____MMMMOOOOTTTTIIIIFFFF____SSSSNNNNAAAAPPPPSSSSHHHHOOOOTTTT conversion.
  105.  
  106.              2. The callback copies the converted data to the
  107.                 clipboard, using XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddCCCCooooppppyyyyBBBByyyyNNNNaaaammmmeeee.
  108.  
  109.              3. When the snapshot data is no longer needed, the
  110.                 callback asks each of the conversion routines
  111.                 associated with widget _w_i_d_g_e_t to convert the snapshot
  112.                 to the _D_O_N_E target, using the distinguisher atom as
  113.                 the selection.
  114.  
  115.           The widget responding to ____MMMMOOOOTTTTIIIIFFFF____SSSSNNNNAAAAPPPPSSSSHHHHOOOOTTTT must own the
  116.           snapshot atom.
  117.  
  118.           The ____MMMMOOOOTTTTIIIIFFFF____SSSSNNNNAAAAPPPPSSSSHHHHOOOOTTTT target takes an optional parameter which
  119.           should be used to distinguish the current selection. If the
  120.           parameter is _N_U_L_L, the conversion routine must allocate a
  121.           distinguisher atom and assign it to the _s_e_l_e_c_t_i_o_n member of
  122.           the XXXXmmmmCCCCoooonnnnvvvveeeerrrrttttCCCCaaaallllllllbbbbaaaacccckkkkSSSSttttrrrruuuucccctttt.
  123.  
  124.           _w_i_d_g_e_t    Specifies the widget that is the source for the
  125.                     data.
  126.  
  127.  
  128.  
  129.      Page 2                                         (printed 10/24/98)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee((((3333XXXX))))    UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV    XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSoooouuuurrrrcccceeee((((3333XXXX))))
  137.  
  138.  
  139.  
  140.           _o_p        Specifies the transfer operation.  Possible values
  141.                     are XXXXmmmmMMMMOOOOVVVVEEEE, XXXXmmmmCCCCOOOOPPPPYYYY, and XXXXmmmmLLLLIIIINNNNKKKK.
  142.  
  143.           _t_i_m_e      Specifies the time of the transfer.  This is
  144.                     usually the timestamp from the event passed to an
  145.                     action routine.  You should call
  146.                     _X_t_L_a_s_t_T_i_m_e_S_t_a_m_p_P_r_o_c_e_s_s_e_d to generate the
  147.                     _t_i_m_evalue.  If you set _t_i_m_e to CCCCuuuurrrrrrrreeeennnnttttTTTTiiiimmmmeeee or 0,
  148.                     UTM will automatically change the call to
  149.                     _X_t_L_a_s_t_T_i_m_e_S_t_a_m_p_P_r_o_c_e_s_s_e_d.
  150.  
  151.      RRRREEEETTTTUUUURRRRNNNN
  152.           This function returns FFFFaaaallllsssseeee if the clipboard is locked or if
  153.           no data is placed on the clipboard.  Otherwise, it returns
  154.           TTTTrrrruuuueeee.
  155.  
  156.      RRRREEEELLLLAAAATTTTEEEEDDDD
  157.           XXXXmmmmQQQQTTTTttttrrrraaaannnnssssffffeeeerrrr(3), XXXXmmmmTTTTrrrraaaannnnssssffffeeeerrrrDDDDoooonnnneeee(3), XXXXmmmmTTTTrrrraaaannnnssssffffeeeerrrrVVVVaaaalllluuuueeee(3),
  158.           XXXXmmmmeeeeCCCClllliiiippppbbbbooooaaaarrrrddddSSSSiiiinnnnkkkk(3), XXXXmmmmeeeeCCCCoooonnnnvvvveeeerrrrttttMMMMeeeerrrrggggeeee(3), XXXXmmmmeeeeDDDDrrrraaaaggggSSSSoooouuuurrrrcccceeee(3),
  159.           XXXXmmmmeeeeDDDDrrrrooooppppSSSSiiiinnnnkkkk(3), XXXXmmmmeeeeGGGGeeeettttEEEEnnnnccccooooddddiiiinnnnggggAAAAttttoooommmm(3), XXXXmmmmeeeePPPPrrrriiiimmmmaaaarrrryyyySSSSiiiinnnnkkkk(3),
  160.           XXXXmmmmeeeePPPPrrrriiiimmmmaaaarrrryyyySSSSoooouuuurrrrcccceeee(3), XXXXmmmmeeeeSSSSeeeeccccoooonnnnddddaaaarrrryyyySSSSiiiinnnnkkkk(3),
  161.           XXXXmmmmeeeeSSSSeeeeccccoooonnnnddddaaaarrrryyyySSSSoooouuuurrrrcccceeee(3), XXXXmmmmeeeeSSSSeeeeccccoooonnnnddddaaaarrrryyyyTTTTrrrraaaannnnssssffffeeeerrrr(3),
  162.           XXXXmmmmeeeeSSSSttttaaaannnnddddaaaarrrrddddCCCCoooonnnnvvvveeeerrrrtttt(3), XXXXmmmmeeeeSSSSttttaaaannnnddddaaaarrrrddddTTTTaaaarrrrggggeeeettttssss(3), and
  163.           XXXXmmmmeeeeTTTTrrrraaaannnnssssffffeeeerrrrAAAAddddddddDDDDoooonnnneeeePPPPrrrroooocccc(3).
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                                         (printed 10/24/98)
  196.  
  197.  
  198.  
  199.